Inside Macintosh: QuickDraw GX Objects /

Chapter 7 - View-Related Objects / View-Related Objects Reference

View Port Functions / Manipulating View Port Object Properties

GXSetViewPortClip

You can use the GXSetViewPortClip function to set the clip property of a view port object.

void GXSetViewPortClip(gxViewPort target, gxShape clip);

target

A reference to the view port whose clip you wish to set.

clip

A reference to a shape object whose geometry describes the clip to be assigned.

DESCRIPTION

The GXSetViewPortClip function copies information from the shape object referenced by the clip parameter into the clip property of the view port object referenced by the target parameter. You can specify nil for the clip parameter, in which case this function sets the clip property of the target view port to a full clip. (A full clip indicates that QuickDraw GX should not apply view port clipping to shapes drawn to this view port.)

Although a filled rectangle shape is most typical for a view port clip, the new clip shape may be a geometric shape, a bitmap shape, or a glyph shape. It may not be a picture, text, or layout shape.

• If you specify a geometric shape, it must be in primitive form--that is, all the stylistic information about the shape must be incorporated into the shape's geometry--because this function copies only the geometry-related information from the shape you specify. It does not copy the information contained in the shape's style. You can convert a shape to its primitive form using the GXPrimitiveShape function, which is described in Inside Macintosh: QuickDraw GX Graphics. You can also specify an empty or full shape for a clip.
• If you specify a bitmap shape, it must have a pixel size of 1 and its color profile reference must be nil. In the bitmap, pixel values of 0 obscure drawing; pixel values of 1 do not restrict visibility. The GXSetViewPortClip function copies the pixel image from the bitmap to the clip property of the target view port.
• If you specify a glyph shape, this function uses information from the glyph shape's style object as well as its style list to determine the size, form, and position of the glyph outlines; those outlines are then used to clip drawing. The style list cannot have nil entries. A style object referenced by the glyph shape cannot be complex--that is, it cannot have a cap, join, dash, pattern, text face, font variation, tag list, or any of the properties used only by layout shapes.

Because it is copied into the view port, changing the clip shape after calling GXSetViewPortClip does not affect the view port's clip.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
invalid_viewPort_reference
colorProfile_must_be_nil	(debugging version)
bitmap_pixel_size_must_be_1	(debugging version)
empty_shape_not_allowed	(debugging version)
ignorePlatformShape_not_allowed	(debugging version)
nil_style_in_glyph_not_allowed	(debugging version)
complex_glyph_style_not_allowed	(debugging version)
illegal_type_for_shape	(debugging version)
shapeFill_not_allowed	(debugging version)
viewPort_is_a_window	(debugging version)
Notices (debugging version)
clip_already_set
tags_in_shape_ignored

SEE ALSO

For examples of the use of this function, see Listing 7-4 on page 7-46 and Listing 7-5 on page 7-47.

For information about geometric shapes and bitmap shapes, see Inside Macintosh: QuickDraw GX Graphics. For information about glyph shapes, see Inside
Macintosh: QuickDraw GX Typography.

To retrieve a copy of the view port clip, use the GXGetViewPortClip function, described in the previous section.